home *** CD-ROM | disk | FTP | other *** search
/ Alles Voor Internet / Tout Pour Internet / alles voor internet.iso / MacInternet™ / Telnet / NCSA / tn3270 2.3d26 source / tn3270 / api.h < prev    next >
Text File  |  1991-06-12  |  20KB  |  513 lines
  1. /* tn3270 API Interface */
  2.  
  3. /* This file defines the content of messages sent to or from the tn3270
  4.    API.  These messages are sent using either the SPPC driver or the
  5.    PPC Toolbox in System 7 and later.  Due to limitations of the SPPC
  6.    driver, the longest message cannot exceed 128 bytes.               */
  7.  
  8. /* Note: all characters strings are C strings (null delimited).        */
  9.  
  10. /* message type values */
  11. #define ErrorResponseType        4001
  12. #define GetIdRequestType        2
  13. #define GetIdResponseType        4002
  14. #define GetCapRequestType        3
  15. #define GetCapResponseType        4003
  16. #define GetVersRequestType        4
  17. #define GetVersResponseType        4004
  18. #define OpenRequestType            5
  19. #define OpenResponseType        4005
  20. #define GetConnStatusType        6
  21. #define GetConnResponseType        4006
  22. #define GetCharRequestType        7
  23. #define GetCharResponseType        4007
  24. #define CloseRequestType        8
  25. #define CloseResponseType        4008
  26. #define CloseNotifyRequestType    9
  27. #define CloseNotifyResponseType    4009
  28. #define CloseEventResponseType    4010
  29. #define GetBuffersRequestType    11
  30. #define GetBuffersResponseType    4011
  31. #define WriteNotifyRequestType    12
  32. #define WriteNotifyResponseType    4012
  33. #define WriteEventResponseType    4013
  34. #define SendDataRequestType        14
  35. #define SendDataResponseType    4014
  36. #define SendLocalRequestType    15
  37. #define SendLocalResponseType    4015
  38.  
  39. /* error response codes */
  40. #define noError                0
  41. #define badMessageType        1
  42. #define badRequestLength    2
  43. #define unimplementedErr    3
  44.  
  45. /* response codes for connection status and open */
  46. #define openResPending        10        /* name resolution in progress */
  47. #define openResFailed        11        /* name resolution failed */
  48. #define    openConnPending        12        /* connection in progress */
  49. #define    openConnFailed        13        /* connection failed */
  50. #define openNegOptions        14        /* option negotiation in progress */
  51. #define    openLineMode        15        /* connection opened in line mode */
  52. #define open3270Mode        16        /* connection opened in 3270 mode */
  53. #define openNoSessions        17        /* no more sessions available */
  54. #define openFormatErr        18        /* invalid screen format specified */
  55. #define openBadId            19        /* (status) no conn. record for msgid */
  56.  
  57. /* response codes for close notification request */
  58. #define closeNotifyActive    30        /* close notification already active */
  59.  
  60. /* close event codes */
  61. #define closeNetFail        31        /* network failure */
  62. #define closeNetClose        32        /* network connection closed */
  63. #define closeAPI            33        /* API request */
  64. #define closeUser            34        /* user action */
  65. #define closeUnknown        35        /* undetermined */
  66.  
  67. /* response codes for write notification request */
  68. #define writeNotifyActive    40        /* write notification already active */
  69.  
  70. /* response codes for send data and send local request */
  71. #define sendLocked            50        /* send rejected- keyboard is locked */
  72. #define sendBadAddress        51        /* cursor address is invalid */
  73. #define sendInsErr            52        /* no room for char. in insert mode */
  74. #define sendAttrErr            53        /* attempt to overwrite attr. byte */
  75. #define sendProtErr            54        /* attempt to store in protected field */
  76. #define sendAIDErr            55        /* invalid AID code specified */
  77. #define sendFmtErr            56        /* invalid for unformatted screen */
  78. #define sendOpErr            57        /* invalid op code for send local */
  79.  
  80. /* API calls for the Session Manager */
  81.  
  82. /* The session manager is called to create new sessions.  Once a
  83.    session is created, all subsequent API calls are made to the
  84.    session itself.  For SPPC, the session manager registers itself
  85.    as "GFTMn", where "n" is a digit from 1 through 8.  For PPC,
  86.    the session manger registers itself as "tn3270 #n".  This form
  87.    of registration allows multiple copies of tn3270 to be running
  88.    at the same time.  "n" will be the lowest number not already
  89.    in use at the time tn3270 is launched.                        */
  90.    
  91. /* Session Manager: Error Response
  92.    If the session manager receives a message type it cannot
  93.    identify, or a request which cannot be executed for some
  94.    reason, it returns an error response structure:                */
  95.  
  96. typedef struct {
  97.     short msgtype;            /* ErrorResponseType */
  98.     short code;                /* error code */
  99.     } ErrorResponse;
  100.  
  101. /* Session Manager: Get Id
  102.    This call returns the signature, name, and reference number of the
  103.    tn3270 application.  The name allows the API client to identify the
  104.    application by the same name the user has assigned to it.                            */
  105.    
  106. typedef struct {
  107.      short    msgtype;            /* GetIdRequestType */
  108.     } GetIdRequest;
  109.     
  110. typedef struct {
  111.     short    msgtype;            /* GetIdResponseType */
  112.     OSType    signature;            /* 4-character application signature */
  113.                                 /* "GFTM" for standard tn3270 */
  114.     short     refnum;                /* app. resource file refnum */        
  115.     unsigned char appname[120];    /* application file name */
  116.     } GetIdResponse;
  117.  
  118. /* Session Manager: GetCapabilities
  119.    This call returns information describing the valid parameters
  120.    for creating new sessions.  The client sends a GetCapRequest
  121.    structure, and the API returns a GetCapResponse structure:    */
  122.    
  123. typedef struct {
  124.      short    msgtype;        /* GetCapRequestType */
  125.     } GetCapRequest;
  126.     
  127. typedef struct {
  128.     short ptsize;            /* point size */
  129.     short rows;                /* number of rows */
  130.     short cols;                /* number of columns */
  131.     } screenformat;
  132.  
  133. typedef struct {
  134.     short    msgtype;        /* GetCapResponseType */
  135.     short    pendsessions;    /* current number of pending sessions */
  136.     short    currsessions;    /* current number of opened sessions */
  137.     short    maxsessions;    /* maximum number of sessions */
  138.     short    numbformats;    /* number of screen formats which follow */ 
  139.     screenformat sizeinfo[2];    /* max. dimensions for each pointsize */
  140.     } GetCapResponse;
  141.  
  142. /* Session Manager: GetVersion
  143.    This call returns the contents of tn3270's 'vers' 1 resource.  The
  144.    client sends a GetVersRequest structure, and the API returns a
  145.    GetVersResponse structure.  If the 'vers' 1 resource is not available
  146.    for some reason, the "verssize" field of the response will be set
  147.    to zero.                                                                */
  148.    
  149. typedef struct {
  150.      short msgtype;                    /* GetVersRequestType */
  151.     } GetVersRequest;
  152.  
  153. typedef struct {
  154.     short msgtype;                    /* GetVersResponseType */
  155.     short verssize;                    /* size of 'vers' 1 resource */
  156.     unsigned char versdata[120];    /* contents of 'vers' 1 resource 
  157.                                        (actual size given by "verssize") */
  158.     } GetVersResponse;
  159.     
  160. /* Session Manager: OpenSession
  161.    This call creates a new session according to the parameters in
  162.    the OpenRequest structure.  The session manager returns an
  163.    OpenResponse structure when the open suceeds, or has failed for
  164.    some reason.    Due to network conditions, it may take as long as
  165.    several minutes before a response is generated.
  166.    Storage for the hostname and windowname strings may be released
  167.    once the OpenResponse is received.                                 */
  168.    
  169. typedef struct {
  170.     short msgtype;                /* OpenRequestType */
  171.     unsigned char *hostname;    /* host name to connect to,
  172.                                    maximum length = 255      */
  173.     unsigned char *windowname;    /* name for new window,
  174.                                    maximum length = 127         */
  175.     screenformat dfltsize;        /* default screen size (24 by 80) */
  176.     screenformat altsize;        /* alternate screen size */
  177.     char hide;                    /* true if window should be hidden */
  178.     char nowsf;                    /* true to suppress WSF support */
  179.     char noalert;                /* true to suppress alerts to user */
  180.     } OpenRequest;
  181.  
  182. typedef struct {
  183.     short msgtype;                /* OpenResponseType */
  184.     short code;                    /* error code (or noError) for open */
  185.     short sppcrefnum;            /* SPPC refnum for new session */
  186.     short ppcportnum;            /* PPC portRefNum for new session */
  187.     unsigned char sppcname[9];    /* SPPC name for new session */
  188.     unsigned char ppcname[21];    /* PPC name for new session */
  189.     } OpenResponse;
  190.  
  191. /* Session Manager: GetConnectionStatus
  192.     This call returns the status of a pending connection.  A
  193.     connection is pending when an open request has been made for
  194.     the connection, but an open response has not been generated
  195.     yet.                                                          */
  196.    
  197. typedef struct {
  198.     short msgtype;                /* GetConnStatusType */
  199.     unsigned long openid;        /* message id of session open request */
  200.     } GetConnStatus;
  201.  
  202. typedef struct {
  203.     short msgtype;                /* GetConnResponseType */
  204.     unsigned long openid;        /* openid from GetConnStatus */
  205.     short statuscode;            /* code for connection status */
  206.     } GetConnResponse;
  207.  
  208. /* API Calls for Sessions */
  209.  
  210. /* For SPPC, each session registers itself as "GFTMn-i", where
  211.    "GFTMn" is the same as the session manager registration, and
  212.    "i" is a digit from 1 through 8.  For PPC, each session registers
  213.    itself as "tn3270 #n session i".  "i" will be the lowest number
  214.    not already in use at the time the session is created.            */        
  215.    
  216. /* Sessions: Error Response
  217.    The error response for a session is the same as for the session
  218.    manager. (See above.)                
  219.                                                                    */
  220.                                                                 
  221. /* Sessions: GetCharacteristics
  222.    This call returns the characteristics of a session.  The client
  223.    sends a GetCharRequest message, and the API responds with a
  224.    GetCharResponse structure:                                    */
  225.  
  226. typedef struct {
  227.     short msgtype;                /* GetCharRequestType */
  228.     unsigned char *hostname;    /* pointer to storage for hostname */
  229.                                 /* must be 256 bytes (or more) */
  230.     unsigned char *windowname;    /* pointer to storage for windowname */
  231.                                 /* must be 128 bytes (or more) */
  232.     } GetCharRequest;
  233.     
  234. typedef struct {
  235.     short msgtype;                /* GetCharResponseType */
  236.     screenformat dfltsize;        /* default screen size (24 by 80) */
  237.     screenformat altsize;        /* alternate screen size */
  238.     char linemode;                /* true for a line mode session */
  239.     char hide;                    /* true if window is hidden */
  240.     char nowsf;                    /* true if WSF suppression was requested */
  241.     char noalert;                /* true if user alerts suppressed */
  242.     } GetCharResponse;
  243.  
  244. /* Sessions: Close
  245.    This calls requests that a session be closed.  The client sends
  246.    a CloseRequest structure, and the API responds with a CloseResponse
  247.    structure.                                                    
  248.    NOTE: tn3270 will not delay session close processing until the
  249.    response to the close request is read by the client.  Since session
  250.    close processing includes deregistering the session, when a close
  251.    is successful, in some cases the close response may never be
  252.    received.  However, this has never occurred during testing.    
  253.    */
  254.     
  255. typedef struct {
  256.     short msgtype;                /* CloseRequestType */
  257.     } CloseRequest;
  258.     
  259. typedef struct {
  260.     short msgtype;                /* CloseResponseType */
  261.     short code;                    /* error code (or noError) for close */
  262.     } CloseResponse;
  263.  
  264. /* Sessions: CloseNotification
  265.    This call allows a client to request notification when a session
  266.    closes.  Notification will occur when a session closes due to a
  267.    client's close request, and also when the session closes for other
  268.    reasons, such as a network problem, or action taken by the user.
  269.    The client sends a CloseNotifyRequest structure, and
  270.    receives a CloseNotifyResponse structure from the API.  In addition,
  271.    the client may, at some time in the future, receive a 
  272.    CloseEventResponse structure when the session closes.
  273.    Only one client may be defined to receive close notification for a
  274.    connection at any given time.
  275.    Notification may be reset at any time.  It is not an error to
  276.    reset notification when it has never been set.
  277.    NOTE: tn3270 will not delay session close processing until the
  278.    close notification is read by the client.  Since session
  279.    close processing includes deregistering the session, when a close
  280.    is successful, in some cases the close notification may never be
  281.    received.  However, this has never occurred during testing.         */   
  282.  
  283. typedef struct {
  284.     short msgtype;                /* CloseNotifyRequestType */
  285.     char notifyflag;            /* true to set, false to reset notify */
  286.     } CloseNotifyRequest;
  287.  
  288. typedef struct {    
  289.     short msgtype;                /* CloseNotifyResponseType */
  290.     short code;                    /* error code (or noError) for request */
  291.     } CloseNotifyResponse;
  292.  
  293. typedef struct {
  294.     short msgtype;                /* CloseEventResponseType */
  295.     short sppcrefnum;            /* SPPC refnum for connection */
  296.     short ppcportnum;            /* PPC portRefNum for connection */
  297.     short code;                    /* error code for cause of close */
  298.     } CloseEventResponse;
  299.  
  300.  
  301. /* Sessions: GetBuffers
  302.    This call allows a client to obtain the addresses of tn3270's
  303.    data and attribute buffers.  The addresses of the internal 
  304.    variables "kblock" and "kblcode" are returned, which indicate
  305.    whether and why the keyboard is locked.  Also, the address of
  306.    the internal variable "curadr" is returned, which contains the
  307.    cursor position.
  308.    
  309.    NOTE: The buffer addresses are provided to allow efficient
  310.          examination of the buffers.  This call is not intended to
  311.          allow the client to modify the buffers or variables, and
  312.          any such use is unsupported.  The effect of modifying
  313.          these data structures is unpredictable, and may change
  314.          in different versions of tn3270.  Use SendDataRequest
  315.          described below to update the buffers.
  316.    
  317.    The data buffer contains the data received in 3270 data streams,
  318.    and consists of one byte for each character position. 
  319.    The data is EBCDIC as received from the host, without being
  320.    translated.  X'1D' is stored in buffer positions corresponding
  321.    to field attributes (created by either the Start Field or
  322.    Start Field Extended orders).  However, the most reliable way
  323.    to test for a field attribute is to examine bit 15 of the
  324.    attribute bits (see below).
  325.    
  326.    The attribute buffer contains attribute information for each
  327.    data character, and consists of 16 bits for each character
  328.    position.  The bits are defined as follows (bit 15 is the most
  329.    significant bit):
  330.    
  331.    bit 15:        0 = data at this screen position
  332.                    1 = attribute byte at this screen position
  333.    bit 14:        0 = GE does not apply to this character
  334.                    1 = GE does apply to this character
  335.    bits 13-8:     For field attributes, these are the bits 5-0 (the
  336.                    least significant 6 bits) of the field attribute.
  337.    bits 7-6:    Character set for the character or field.  00 is the
  338.                    default character set; 01 is the APL/Text character
  339.                 set.  Other values are currently undefined, and
  340.                 map to the default character set.
  341.    bit 5:        Selection bit: set if this character is included
  342.                    in text selection (as done with the mouse).
  343.    bits 4-3:    Extended highlighting:
  344.                        00 = none
  345.                     01 = blink
  346.                     10 = reverse
  347.                     11 = underscore
  348.    bits 2-0:    Color:
  349.                        000 = default (green)
  350.                     001 = blue
  351.                     010 = red
  352.                     011 = pink
  353.                     100 = green
  354.                     101 = turquoise
  355.                     110 = yellow
  356.                     111 = white
  357.     
  358.     "kblock" is a single byte which is 0 when the keyboard is
  359.     unlocked, and 1 when the keyboard is locked.
  360.  
  361.     "kblcode" is a single byte with the following definition:
  362.         0 = keyboard is unlocked
  363.         1 = keyboard is locked: last write from host did not
  364.             unlock the keyboard
  365.         2 = keyboard is locked: waiting for host to respond
  366.             to last read response transmitted
  367.         3 = keyboard is locked due to communications error
  368.         4 = keyboard is locked due to no active session (should
  369.             not happen during API use)
  370.             
  371.     "curadr" is the screen offset of the cursor.  It is a 16-bit
  372.     unsigned integer.
  373.                                                                 */
  374.                                                                 
  375. typedef struct {
  376.     short msgtype;                /* GetBuffersRequestType */
  377.     } GetBuffersRequest;
  378.     
  379. typedef struct {
  380.     short msgtype;                /* GetBuffersResponseType */
  381.     unsigned char *databuff;    /* data buffer pointer */
  382.     unsigned short *attrbuff;    /* attribute buffer pointer */
  383.     unsigned char *kblock;        /* address of "kblock" */
  384.     unsigned char *kblcode;        /* address of "kblcode" */
  385.     unsigned short *curadr;        /* address of "curadr" */
  386.     } GetBuffersResponse;
  387.     
  388. /* Sessions: WriteNotification
  389.    This call allows the client to request notification of changes
  390.    to the data and attribute buffers.  Notification will occur
  391.    when any changes to the buffer contents are made due to write
  392.    commands received from the host.  Notification will also occur
  393.    when the host issues a read command.  Notification will not occur
  394.    when changes are made due to API or user-entered screen updates.
  395.    Only one client may be defined to receive write notification for
  396.    a connection at any given time.                                */
  397.    
  398. typedef struct {
  399.     short msgtype;                /* WriteNotifyRequestType */
  400.     char notifyflag;            /* true to set, false to reset notify */
  401.     } WriteNotifyRequest;
  402.     
  403. typedef struct {
  404.     short msgtype;                /* WriteNotifyResponseType */
  405.     short code;                    /* error code (or noError) for request */
  406.     } WriteNotifyResponse;
  407.     
  408. typedef struct {
  409.     short msgtype;                /* WriteEventResponseType */
  410.     short sppcrefnum;            /* SPPC refnum for connection */
  411.     short ppcportnum;            /* PPC portRefNum for connection */
  412.     unsigned char ccwop;        /* CCW op-code for this operation */
  413.                                 /* or 0 for line mode write */
  414.     } WriteEventResponse;
  415.  
  416.  
  417. /* Sessions: SendData
  418.    SendData allows the client to do any of the following, in order:
  419.            (1) set the current cursor address
  420.         (2) modify the data and attribute buffers
  421.         (3) send screen modifications to the host, with a specified
  422.              AID code.  An appropriate data stream for the given AID
  423.             code will be generated.                                
  424.     Data will be entered into the data buffer exactly as specified
  425.     in the data field, starting at the cursor address.  The cursor
  426.     address will then be updated following the same rules as for
  427.     user input.  Graphics Escape (GE) may be specified for a character
  428.     by preceding it by GE (X'08') in the data.  GE will never be stored
  429.     in the buffer, and is not included in the returned count of stored
  430.     characters.  
  431.     If the keyboard is locked, all three operations will be skipped,
  432.     and the response code "sendLocked" will be returned.        
  433.     If the cursor address is invalid, all three operations will be
  434.     skipped, and the response code "sendBadAddress" will be returned.
  435.     If a data character cannot be stored, the "code" field of the
  436.     response will indicate the type of error, and the "count" field
  437.     will contain the number of characters successfully stored.  Also,
  438.     any AID code specified will not be transmitted.
  439.     If an invalid AID code is specified, no AID code will be sent,
  440.     and the "code" field of the response will contain an error code.
  441.     For line mode sessions, steps 1 and 3 are skipped, and the data
  442.     consists of ASCII characters to be sent to the host.  In this case,
  443.     no errors are returned.                                            */
  444.     
  445. typedef struct {
  446.     short msgtype;                /* SendDataRequestType */
  447.     unsigned short curadr;        /* cursor address (screen offset),
  448.                                    or 65535 (-1) to leave unchanged */
  449.     unsigned char aidcode;        /* AID code to send, or 0 to skip */
  450.     unsigned char spare;        /* unused- set to 0 */
  451.     short length;                /* length of data to store, or 0
  452.                                     to skip    */
  453.     unsigned char data[120];    /* data to store */
  454.     } SendDataRequest;
  455.     
  456. typedef struct {
  457.     short msgtype;                /* SendDataResponseType */
  458.     short code;                    /* response code (or noError) */
  459.     short count;                /* number of characters stored */
  460.     unsigned short curadr;        /* ending cursor address */
  461.     } SendDataResponse;
  462.  
  463.  
  464. /* Sessions: SendLocal allows the client to perform a local terminal
  465.    operation.  A sequence of operation codes is sent in the data
  466.    field of the request.  If the keyboard is locked, SendLocal will
  467.    be rejected with the response code "sendLocked".  However, an
  468.    exception is that "reset" as the first local operation specified
  469.    will unlock the keyboard.  If an operation produces an error,
  470.    subsequent operations will not be performed.  The "code" field
  471.    in the response will indicated the type of error, and the "count"
  472.    field will indicate the number of completed operations.
  473.  
  474.    The operation codes are:
  475.            1    cursor up
  476.         2    cursor down
  477.         3    cursor left
  478.         4    cursor right
  479.         5    tab
  480.         6    backtab
  481.         7    newline
  482.         8    home
  483.         9    erase eof
  484.         10    erase input
  485.         11    toggle insert mode
  486.         12  delete character
  487.         13    reset keyboard
  488.         14    dup
  489.         15    field mark
  490.         16    toggle APL mode
  491.         17    insert blank
  492.         18    rubout
  493.         19    cursor up twice
  494.         20    cursor down twice
  495.         21    cursor left twice
  496.         22    cursor right twice
  497.         23    toggle cursor position display
  498.                                                                 */        
  499.    
  500. typedef struct {
  501.     short msgtype;                /* SendLocalRequestType */
  502.     short length;                /* length of data field */
  503.     long spare;                    /* unused- set to zero */
  504.     unsigned char data[120];    /* list of operation codes */
  505.     } SendLocalRequest;
  506.     
  507. typedef struct {
  508.     short msgtype;                /* SendLocalResponseType */
  509.     short code;                    /* response code (or noError) */
  510.     short count;                /* count of op codes executed */
  511.     unsigned short curadr;        /* ending cursor address */
  512.     } SendLocalResponse;
  513.